What is traverse?
The traverse npm package is a comprehensive tool for traversing and transforming JavaScript objects. It allows you to easily navigate through objects, arrays, and other nested structures, and apply functions to their elements. It's particularly useful for manipulating complex data structures, applying transformations, and extracting information in a flexible manner.
What are traverse's main functionalities?
Traversing and modifying objects
This feature allows you to traverse through an object and modify elements. In the code sample, the value 2 in the array under key 'a' is updated to 222.
var traverse = require('traverse');
var obj = { a: [1, 2, 3], b: 4 };
traverse(obj).forEach(function (x) {
if (x === 2) this.update(222);
});
Cloning and transforming objects
This feature enables deep cloning of objects with the option to apply transformations during the cloning process. In the example, all numbers in the object are multiplied by 100.
var traverse = require('traverse');
var obj = { a: 1, b: [2, 3] };
var clone = traverse(obj).map(function (node) {
if (typeof node === 'number') this.update(node * 100);
});
Extracting specific elements
This feature is useful for extracting leaf nodes from a complex object structure. The code sample demonstrates how to collect all leaf nodes (elements without child nodes) into an array.
var traverse = require('traverse');
var obj = { a: 1, b: { c: 2, d: [3, 4] } };
var leaves = traverse(obj).reduce(function (acc, x) {
if (this.isLeaf) acc.push(x);
return acc;
}, []);
Other packages similar to traverse
lodash
Lodash is a utility library that provides functions for common programming tasks, including object manipulation. While it offers some similar functionalities for traversing and manipulating objects, it's more general-purpose compared to traverse, which is specifically designed for deep traversal and transformation of objects.
ramda
Ramda is a functional programming library that emphasizes immutability and side-effect free functions. It includes utilities for working with objects in a functional manner. Compared to traverse, Ramda offers a broader set of functional programming tools but might require more setup for deep object traversal and transformation tasks.
traverse ![Version Badge](https://versionbadg.es/ljharb/traverse.svg)
![Downloads](https://img.shields.io/npm/dm/traverse.svg)
![npm badge](https://nodei.co/npm/traverse.png?downloads=true&stars=true)
Traverse and transform objects by visiting every node on a recursive walk.
examples
transform negative numbers in-place
negative.js
var traverse = require('traverse');
var obj = [ 5, 6, -3, [ 7, 8, -2, 1 ], { f : 10, g : -13 } ];
traverse(obj).forEach(function (x) {
if (x < 0) this.update(x + 128);
});
console.dir(obj);
Output:
[ 5, 6, 125, [ 7, 8, 126, 1 ], { f: 10, g: 115 } ]
collect leaf nodes
leaves.js
var traverse = require('traverse');
var obj = {
a : [1,2,3],
b : 4,
c : [5,6],
d : { e : [7,8], f : 9 },
};
var leaves = traverse(obj).reduce(function (acc, x) {
if (this.isLeaf) acc.push(x);
return acc;
}, []);
console.dir(leaves);
Output:
[ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
scrub circular references
scrub.js:
var traverse = require('traverse');
var obj = { a : 1, b : 2, c : [ 3, 4 ] };
obj.c.push(obj);
var scrubbed = traverse(obj).map(function (x) {
if (this.circular) this.remove()
});
console.dir(scrubbed);
output:
{ a: 1, b: 2, c: [ 3, 4 ] }
methods
Each method that takes an fn
uses the context documented below in the context
section.
.map(fn)
Execute fn
for each node in the object and return a new object with the
results of the walk. To update nodes in the result use this.update(value)
.
.forEach(fn)
Execute fn
for each node in the object but unlike .map()
, when
this.update()
is called it updates the object in-place.
.reduce(fn, acc)
For each node in the object, perform a
left-fold
with the return value of fn(acc, node)
.
If acc
isn't specified, acc
is set to the root object for the first step
and the root element is skipped.
.paths()
Return an Array
of every possible non-cyclic path in the object.
Paths are Array
s of string keys.
.nodes()
Return an Array
of every node in the object.
.clone()
Create a deep clone of the object.
.get(path)
Get the element at the array path
.
.set(path, value)
Set the element at the array path
to value
.
.has(path)
Return whether the element at the array path
exists.
context
Each method that takes a callback has a context (its this
object) with these
attributes:
this.node
The present node on the recursive walk
this.path
An array of string keys from the root to the present node
this.parent
The context of the node's parent.
This is undefined
for the root node.
this.key
The name of the key of the present node in its parent.
This is undefined
for the root node.
this.isRoot, this.notRoot
Whether the present node is the root node
this.isLeaf, this.notLeaf
Whether or not the present node is a leaf node (has no children)
this.level
Depth of the node within the traversal
this.circular
If the node equals one of its parents, the circular
attribute is set to the
context of that parent and the traversal progresses no deeper.
this.update(value, stopHere=false)
Set a new value for the present node.
All the elements in value
will be recursively traversed unless stopHere
is
true.
this.remove(stopHere=false)
Remove the current element from the output. If the node is in an Array it will
be spliced off. Otherwise it will be deleted from its parent.
this.delete(stopHere=false)
Delete the current element from its parent in the output. Calls delete
even on
Arrays.
this.before(fn)
Call this function before any of the children are traversed.
You can assign into this.keys
here to traverse in a custom order.
this.after(fn)
Call this function after any of the children are traversed.
this.pre(fn)
Call this function before each of the children are traversed.
this.post(fn)
Call this function after each of the children are traversed.
install
Using npm do:
$ npm install traverse
license
MIT